<html>
  <head>
    <title>TraffoSim README</title>
    <meta name="author" content="Mark Stillwell"/>
  </head>
  <body>
    <center>
      <h1>ReadMe</h1>
      <A HREF="http://code.google.com/p/traffometer-sim-grey/">TraffoSim Grey</A><br />
      <A HREF="http://www.hawaii.edu/">University of Hawaii</A><br />
    </center>
    <p>This file introduces you to the major components of this software package. It includes
    information on the contents of the package you have downloaded, instructions on how to install
    the system, basic invocation and usage, user documentation, developer documentation, and contact
    coordinates for further information.</p>
    <h2>A. Contents of this package</h2>
    <table width="735" border="1">
      <tr>
        <th align="center" valign="top" width="93">Directory/File</th>
        <th valign="top" width="626">Contents</th>
      </tr>
      <tr>
        <td align="center" valign="top" width="93">.</td>
        <td valign="top" width="626">
          Top-level directory files include:
          <ul>
            <li>README.html (this document)</li>
            <li>
              analyze.build.xml (runs automated tests, sends results to hackystat, builds reports)
            </li>
            <li>build.xml (contains basic build targets and property definitions)</li>
            <li>checkstyle.build.xml (runs checkstyle)</li>
            <li>demo.build.xml (runs demonstration)</li>
            <li>emma.build.xml (runs emma to generate coverage data</li>
            <li>findbugs.build.xml (runs findbugs)</li>
            <li>javadoc.build.xml (creates javadocs)</li>
            <li>junit.build.xml (runs junit)</li>
            <li>pmd.build.xml (runs PMD)</li>
            <li>there may also be other *.build.xml files.&nbsp;</li>
          </ul>
        </td>
      </tr>
      <tr>
        <td align="center" valign="top" width="93">./lib</td>
        <td valign="top" width="626">
          Contains data files used to build and/or run the system:
          <ul>
            <li>checkstyle/ (contains checkstyle customizations)</li>
            <li>pmd/ (contains pmd customizations)</li>
            <li>findbugs/ (contains findbugs customizations)</li>
            <li>config/ (contains sample configurations)</li>
            <li>jar/ (contains java libraries in jar files)</li>
          </ul>
        </td>
      </tr>
      <tr>
        <td align="center" valign="top" width="93">./doc</td>
        <td valign="top" width="626">
          Contains developer documentation including:
          <ul>
            <li>
              <a href="doc/LicenseInfo.html">LicenseInfo.html</a> 
              provides licenses for use of all software included with this system.
            </li>
            <li>
              <a href="doc/History.html">History.html</a>
              provides a chronological record of the releases of this system.
            </li>
          </ul>
        </td>
      </tr>
      <tr>
        <td align="center" valign="top" width="93">./src</td>
        <td valign="top" width="626">Contains the source files.</td>
      </tr>
      <tr>
        <td align="center" valign="top" width="93">./build</td>
        <td valign="top" width="626">
          Contains various products of the build process, including:
          <ul>
            <li>
              <a href="./build/checkstyle/">checkstyle/</a> 
              (contains output from checkstyle, created by 'ant -f checkstyle.build.xml')
            </li>
            <li>
              <a href="./build/emma/">emma/</a> 
              (contains coverage data compiled by emma, created by 'ant -f emma.build.xml')
            </li>
            <li>
              <a href="./build/findbugs/">findbugs/</a>
              (contains output from findbugs, created by 'ant -f findbugs.build.xml')
            </li>
            <li>
              <a href="./build/javadoc/">javadoc/</a>
              (contains javadocs, created by 'ant -f javadoc.build.xml')
            </li>
            <li>
              <a href="./build/junit/">junit/</a>
              (contains output from the JUnit tests, created by 'ant -f junit.build.xml')
            </li>
            <li>
              <a href="./build/pmd/">pmd/</a>
              (contains output from pmd, created by 'ant -f pmd.build.xml')
              </li>
          </ul>
          <p>These links will not work until their corresponding ant target has been executed.</p>
        </td>
      </tr>
    </table>
    <h2>B. Basic Installation</h2>
    <p>These instructions assume that you have checked the TraffoSim build system out of the 
    svn repository located at 
    <a 
      href="http://traffometer-sim-aqua.googlecode.com/svn/trunk/"
    >http://traffometer-sim-aqua.googlecode.com/svn/trunk/</a>.</p>
    <h3>B1: Install Java 1.5</h3>
    <ul>
      <li>
        Install the Java JDK (the full JDK, not just the JRE) by following the instructions at 
        <a href="http://java.sun.com/">http://java.sun.com/</a>.
      </li>
      <li>
        Set the JAVA_HOME environment variable to point to your Java installation (for example, 
        <a href="file:///c:/java/jdk1.5.0_08">c:\java\jdk1.5.0_08</a>)
      </li>
      <li>Add JAVA_HOME/bin to your PATH variable.</li>
    </ul>
    <h3>B2: Install Ant 1.7</h3>
    <ul>
      <li>
        Download and unzip apache-ant-1.7.0Beta1.zip (or later) from 
        <a href="http://ant.apache.org/">http://ant.apache.org/</a>.
      </li>
      <li>
        Set the ANT_HOME environment variable to point to your Ant installation (for example, 
        <a href="file:///c:/apache-ant-1.7.0Beta1">c:\apache-ant-1.7.0Beta1</a>)
      </li>
      <li>Add ANT_HOME/bin to your PATH variable.</li>
    </ul>
    <h3>B3: Install HackyStat</h3>
    <ul>
      <li>
        Download the hackystat installer from
        <a href="http://hackystat.ics.hawaii.edu/">http://hackystat.ics.hawaii.edu/</a>.
      </li>
      <li>
        Run the installer and make sure to install the sensors for Ant, Checkstyle, Eclipse, Emma, 
        Findbugs, Junit, PMD, and Subversion.
      </li>
    </ul>
    <h3>B4: Install JUnit 4.1</h3>
    <ul>
      <li>
        Download and unzip junit4.1.zip from 
        <a href="http://www.junit.org/">http://www.junit.org/</a>.
      </li>
      <li>
        Set the JUNIT_HOME environment variable to point to your JUnit installation 
        (for example, <a href="file:///c:/java/junit-4.1">c:\java\junit-4.1</a>)
      </li>
    </ul>
    <h3>B5: Install Emma 2.0.5312</h3>
    <ul>
      <li>
        Download and unzip emma-2.0.5312.zip from 
        <a href="http://emma.sourceforge.net/">http://emma.sourceforge.net/</a>.
      </li>
      <li>
        Set the EMMA_HOME environment variable to point to your Emma installation (for example, 
        <a href="file:///c:/java/emma-2.0.5312">c:\java\emma-2.0.5312</a>.)
      </li>
    </ul>
    <h3>B6: Configure Eclipse for building the system</h3>
    <ul>
      <li>
        Under Window | Preferences | Java | Build Path | Classpath Variables, create three new 
        Classpath Variables called ANT_HOME, CATALINA_HOME, and HTTPUNIT_HOME. The values of these
        classpath variables should be the same as their corresponding environment variables.
      </li>
      <li>
        After you have done this, you should be able to import this project into your Eclipse 
        workspace without error.
      </li>
    </ul>
    <h3>B7: Install CheckStyle 4.2 (Optional)</h3>
    <ul>
      <li>
        Download and unzip checkstyle-4.2.zip from 
        <a href="http://checkstyle.sourceforge.net/">http://checkstyle.sourceforge.net/</a>.
      </li>
      <li>
        Set the CHECKSTYLE_HOME environment variable to point to your Checkstyle installation 
        (for example, <a href="file:///c:/java/checkstyle-4.2">c:\java\checkstyle-4.2</a>.)
      </li>
    </ul>
    <h3>B8: Install FindBugs 1.0.0 (Optional)</h3>
    <ul>
      <li>
        Download and unzip findbugs-1.0.0.zip from 
        <a href="http://findbugs.sourceforge.net/">http://findbugs.sourceforge.net/</a>.
      </li>
      <li>
        Set the FINDBUGS_HOME environment variable to point to your FindBugs installation 
        (for example, <a href="file:///c:/java/findbugs-1.0.0">c:\java\findbugs-1.0.0</a>.)
      </li>
    </ul>
    <h3>B9: Install PMD 3.7 (Optional)</h3>
    <ul>
      <li>
        Download and unzip pmd-3.7.zip from 
        <a href="http://pmd.sourceforge.net/">http://pmd.sourceforge.net/</a>.
      </li>
      <li>
        Set the PMD_HOME environment variable to point to your PMD installation 
        (for example, <a href="file:///c:/java/pmd-3.7">c:\java\pmd-3.7</a>.)
      </li>
    </ul>    
    <h3>B10: Install SCLC 2.4.525 (Optional)</h3>
    <ul>
      <li>
        Download and unzip sclc-2.4.525.zip from 
        <a href="http://csdl.ics.hawaii.edu/Tools/SCLC/">http://csdl.ics.hawaii.edu/Tools/SCLC/</a>.
      </li>
      <li>
        Set the SCLC_HOME environment variable to point to your SCLC installation 
        (for example, <a href="file:///c:/java/sclc-2.4.525">c:\java\sclc-2.4.525</a>.)
      </li>
    </ul>   
    <h2>C. Invocation</h2>
    <h3>C1: Basic compilation</h3>
    <p>To perform a basic compilation, invoke &quot;ant&quot;</p>
    <h3>C2: Creating a Jar file</h3>
    <p>To create a jar file, invoke 'ant jar'.</p>
    <h3>C3: Running JUnit Tests</h3>
    <p>To run the JUnit tests over the system, invoke 'ant -f junit.build.xml'.</p>
    <h3>C4: Running Emma to get coverage data.</h3>
    <p>To determine the coverage associated with the unit tests, invoke 'ant -f emma.build.xml'.</p>
    <h3>C5: Running Checkstyle</h3>
    <p>To run the Checkstyle over the system, invoke 'ant -f checkstyle.build.xml'.</p>
    <h3>C6: Running Findbugs</h3>
    <p>To run the FindBugs over the system, invoke 'ant -f findbugs.build.xml'.</p>
    <h3>C7: Running PMD</h3>
    <p>To run the PMD over the system, invoke 'ant -f pmd.build.xml'.</p>
    <h3>C8: Running SCLC</h3>
    <p>To run the SCLC over the system, invoke 'ant -f sclc.build.xml'.</p>
    <h3>C9: Running the Demo</h3>
    <p>To run the demo, first make sure that TraffoBase is also running on the same system in demo
    mode, then invoke 'ant -f demo.build.xml'.</p>
    <h3>C10: Running the Configuration Wizard GUI demo.</h3>
    <p>To run the demo, first make sure that TraffoBase is also running on the same system in demo
    mode, then invoke 'ant -f demogui.build.xml'.</p>
    <h2>D. User documentation</h2>
    <p>To run traffosim, invoke 
    'java -jar &lt;jarfile&gt; -config &t;configfile&gt; {-server &lt;server&gt; | -list }'.  The 
    &lt;configfile&gt; option should specify the path to a valid TraffoSim configuration file.  
    Either the '-server &lt;server&gt;' or '-list' option must be specified.  If '-list' is 
    specified the TraffoPackets to be sent will be printed to the screen rather than being sent to a
    TraffoBase server.</p>
    <h2>E. Developer documentation</h2>
    <p>This distribution includes Eclipse project definition files. In addition, it includes the 
    following developer build files and targets. For the external tools (Checkstyle, PMD, FindBugs,
    JUnit, SCLC), you must download them from their home pages, unzip them, and then set an 
    environment variable (CHECKSTYLE_HOME, PMD_HOME, etc.) to point to this directory.</p>
    <table border="1" width="100%">
      <tr>
        <td width="22%" valign="top">
          checkstyle.build.xml
          <p>Requires: checkstyle 4.2</p>
        </td>
        <td width="78%" valign="top">
          Runs <a href="http://checkstyle.sourceforge.net/">Checkstyle</a> on the system, using 
          rules in lib/checkstyle/checkstyle.modules.xml
          <p>Invocation: ant -f checkstyle.build.xml</p>
        </td>
      </tr>
      <tr>
        <td width="22%" valign="top">
          junit.build.xml
          <p>Requires: JUnit 4.1</p>
        </td>
        <td width="78%" valign="top">
          Runs <a href="http://www.junit.org/">JUnit</a> on the system, using Test case code in 
          src/**/Test*.java.
          <p>Invocation: ant -f junit.build.xml</p>
        </td>
      </tr>
      <tr>
        <td width="22%" valign="top">
          emma.build.xml
          <p>Requires: Emma 2.0.5312 and JUnit</p>
        </td>
        <td width="78%" valign="top">
          Runs <a href="http://emma.sourceforge.net/">Emma</a> on the system, using Test case code 
          in src/**/Test*.java.
          <p>Invocation: ant -f emma.build.xml</p>
        </td>
      </tr>
      <tr>
        <td width="22%" valign="top">javadoc.build.xml</td>
        <td width="78%" valign="top">
          Runs JavaDoc on the system.
          <p>Invocation: ant -f javadoc.build.xml</p>
        </td>
      </tr>
      <tr>
        <td width="22%" valign="top">
          findbugs.build.xml
          <p>Requires: FindBugs 1.0.0</p>
        </td>
        <td width="78%" valign="top">
          Runs <a href="http://findbugs.sourceforge.net/">FindBugs</a> on the system, using rules in
          lib/findbugs/findbugs.filter.xml
          <p>Invocation: ant -f findbugs.build.xml</p>
        </td>
      </tr>
      <tr>
        <td width="22%" valign="top">
          pmd.build.xml
          <p>Requires: PMD 3.7</p>
        </td>
        <td width="78%" valign="top">
          Runs <a href="http://pmd.sourceforge.net/">PMD</a> on the system, using rules in 
          lib/pmd/pmd.rulesets.xml
          <p>Invocation: ant -f pmd.build.xml</p>
        </td>
      </tr>
      <tr>
        <td width="22%" valign="top">
          sclc.build.xml
          <p>Requires: SCLC 2.4.525</p>
        </td>
        <td width="78%" valign="top">
          Runs <a href="http://csdl.ics.hawaii.edu/Tools/SCLC/">SCLC</a> on the system.
          <p>Invocation: ant -f sclc.build.xml</p>
        </td>
      </tr>
    </table>
    <h2>F. Contact information</h2>
    <p>If you would like to know more about this software, or would like to be informed of future 
    releases:</p>
    <ul>
      <li>
        <b>Home page:</b> 
        <a 
          href="http://code.google.com/p/traffometer-sim-grey/"
        >http://code.google.com/p/traffometer-sim-grey/</a>
      </li>
      <li>
        <b>Developer contact:</b><br />
        <ul>
          <li><a href="mailto:kiet@hawaii.edu">Kiet Huynh &lt;kiet@hawaii.edu&gt;</a></li>
          <li><a href="mailto:gelee@hawaii.edu">George Lee &lt;gelee@hawaii.edu&gt;</a></li>
          <li><a href="mailto:elaynem@hawaii.edu">Elayne Man &lt;elaynem@hawaii.edu&gt;</a></li>
        </ul>
      <li>
        <b>Configuration management repository:</b>
        <a
          href="http://traffometer-sim-grey.googlecode.com/svn/trunk/"
        >http://traffometer-sim-grey.googlecode.com/svn/trunk/</a>
      </li>
      <li>
        <b>Developer and user mailing lists:</b><br />
        <ul>
          <li>
            <a 
              href="mailto:traffometer-sim-grey-discuss@googlegroups.com"
            >TraffoSim Grey Discussion &lt;traffometer-sim-grey-discuss@googlegroups.com&gt;</a>
          </li>
          <li>
            <a 
              href="mailto:traffometer-sim-grey-svn@googlegroups.com"
            >TraffoSim Grey SVN &lt;traffometer-sim-grey-svn@googlegroups.com&gt;</a>
          </li>
        </ul>
      </li>
    </ul>
  </body>
</html>